home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Night of the Living Disc / Night of the Living Disc.hdv / Dev.CD.5 / Tools / Technical.Notes / IIGS / TN.IIGS.073 < prev    next >
Encoding:
Text File  |  1990-04-29  |  5.0 KB  |  102 lines  |  [04] ASCII Text (0x0000)
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #73:    Using User Tool Sets
  9.  
  10. Revised by:    Dave Lyons                                            May 1990
  11. Written by:    Dave Lyons                                       November 1989
  12.  
  13. This Technical Note explains how to write a user tool set and why writing a 
  14. user tool set is better than stealing a system tool set number.
  15. Changes since November 1989:  Added a caution that a function's entry point 
  16. must not be at the first byte of a bank.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. The Apple IIgs Toolbox Reference describes system tool sets, which are usually 
  21. called through the system tool dispatcher vectors 1 ($E10000) and 2 ($E10004).
  22.  
  23. There are 255 possible system tool set numbers (1 through 255).  All of these 
  24. are reserved for definition by the system.  If your program is "borrowing" a 
  25. system tool set number, please feel guilty and switch over to the user tool 
  26. set numbers.  There are 255 of them too, and they're called through user tool 
  27. dispatcher vectors 1 ($E10008) and 2 ($E1000C).  All 255 user tool set numbers 
  28. are available for the current application to use as it chooses.  (Desk 
  29. accessories are forbidden to use user tool sets.)
  30.  
  31. Of the four tool dispatcher vectors, only the first one ($E10000) has received 
  32. a lot of publicity.  $E10008  works just like $E10000, except that it passes 
  33. control to a user tool set instead of a system tool set.
  34.  
  35. The second vector of each pair ($E10004 and $E1000C) works just like the 
  36. first, except that one extra RTL address must be pushed onto the stack after 
  37. any parameters are pushed.  This way you can have a subroutine to do some or 
  38. all of your toolbox dispatching, and that subroutine can do extra processing 
  39. before or after the tool call, or both.
  40.  
  41.  
  42. How Can I Write a User Tool Set?
  43.  
  44. Appendix A of Toolbox Reference, Volume 2, shows how to write a user tool set.  
  45. Your tool set's Work Area Pointer is a four-byte value you can set with SetWAP 
  46. and get with GetWAP.  The WAP value is already loaded into the Y and A 
  47. registers every time one of your tool set's functions gets control.  The 
  48. traditional use for the WAP is to keep track of an area of memory owned by 
  49. your tool set.  (SetTSPtr calls your xxxBootInit function.)
  50.  
  51. If you do use the WAP in a conventional way, your xxxStatus function should 
  52. return TRUE if the WAP is nonzero; your xxxStartUp function should set the WAP 
  53. to a non-zero value pointing to some memory space you own (provided by the 
  54. caller, or allocated with NewHandle using a memory ID provided by the caller); 
  55. and your xxxShutDown function should set the WAP back to zero.
  56.  
  57. Since the X register contains the tool set and function number when one of 
  58. your functions gets control, it is not necessary for a tool set to be written 
  59. to be used as a predetermined user tool set number.  At execution time, your 
  60. tool set can compute the proper error codes and values to send to GetWAP and 
  61. SetWAP.
  62.  
  63. Note:  At the bottom of page A-8 of the Apple IIGS Toolbox 
  64.        Reference, Volume 2, "lda #$90" should read "lda #$8100" for 
  65.        version 1.0 prototype.  On page A-10, the figure should show two 
  66.        RTL addresses (6 bytes) on the stack.
  67.  
  68.  
  69. How Can I Load My Tool Set From Disk?
  70.  
  71. One way to load your tool set from disk is to use InitialLoad or InitialLoad2, 
  72. supplying a pathname like "9:MyToolset" (prefix 9 is initially set to the 
  73. directory containing your application; prefix 1 also works, but its length is 
  74. limited to 64 characters).  You can then use SetTSPtr to tell the Tool Locator 
  75. about your tool set, as shown in Appendix A.
  76.  
  77. When you're done with your tool set, call UserShutdown on the memory ID 
  78. returned by InitialLoad, so the memory it's using is disposed of or made 
  79. purgeable.  (You can shut it down and allow it to remain in memory in a 
  80. purgeable state; if you do this, you should try to revive your tool set with 
  81. Restart before you try InitialLoad or InitialLoad2.)
  82.  
  83. When your application quits and calls TLShutDown, the system disconnects your 
  84. tool set from the user tool set TPT.  If the UserShutDown is not  followed 
  85. immediately by the TLShutDown, you may wish to use SetTSPtr to cleanly remove 
  86. your tool set from the system (set the tool set pointer so that it points at a 
  87. zero word).
  88.  
  89. Note:  Because of the way the tool dispatcher transfers control to 
  90.        toolbox functions, a function's entry point must not be at the 
  91.        first byte of a bank ($xx0000).  This is normally not an issue, 
  92.        since it's common to put the actual code right after the function 
  93.        pointer table, all in one load segment.  Just make sure no 
  94.        function begins at the first byte of a load segment, and you're 
  95.        safe.
  96.  
  97.  
  98. Further Reference
  99. _____________________________________________________________________________
  100.     o    Apple IIGS Toolbox Reference, Volume 2
  101.     o    GS/OS Reference, Volume 2
  102.